<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!--  
     Copyright  2009  Sun Microsystems, Inc. All rights reserved.
-->
<HTML>
<HEAD>
        <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
        <TITLE>Package Summary </TITLE>
	<!-- Changed  30-Mar-2005 -->
        <META NAME="GENERATOR" CONTENT="StarOffice 6.0  (Solaris Sparc)">
        <META NAME="CREATED" CONTENT="20030626;13530100">
        <META NAME="CHANGED" CONTENT="20030716;10435900">
</HEAD>
<BODY LANG="en-US">
<p>
  The Content Handler API and execution model let an application
  invoke registered J2ME and non-Java applications by URL, by content
  type, or by content handler ID.
  The application can use actions provided by the handler on the 
  invoked content. For example, the application can use the handler to 
  get a specific display, or it can use other content handler capabilities 
  such as open, print, and play. 
  For example, an application such as a MIDP MIDlet or a Personal
  Profile Xlet can  
  be registered to handle the MIME type <code>image/png</code>.
  Other applications can then request the handler to display the
  image. The handler can provide multiple actions
  that control how the content is displayed, modified, or
  returned. The execution model
  leverages the device's application management software (AMS) to
  provide a smooth user experience, to
  control the execution of the applications, to conserve resources,
  and to enforce the security policy of the device and the Java
  runtime environment. 

<p>This optional package is designed to be compatible with any J2ME
  profile including the
  <A HREF="http://jcp.org/en/jsr/detail?id=118"> 
    Mobile Information Device Profile Version 2.0</A>,
  <A HREF="http://jcp.org/en/jsr/detail?id=37">
    Mobile Information Device Profile Version 1.0</A>, 
  <A HREF="http://jcp.org/en/jsr/detail?id=195">
    Information Module Profile Version 1.0</A>, the
  <A HREF="http://jcp.org/en/jsr/detail?id=129"> 
    Personal Basis Profile</a>, and other compatible profiles. </p>

<P>The specification includes functions to:</P>
<ul>
  <li>Invoke a content handler and get a response</li>
  <li>Register a content handler</li>
  <li>Query registrations</li>
  <li>Respond to an invocation</li>
</ul>
<P>Registration allows a packaged J2ME application, for example an
  Xlet in a Personal Basis Profile (PBP)
  application, to be associated with one or more content types and to be 
  invoked from other applications to handle content. 
  Multiple content handlers can be registered for the types, suffixes
  and actions.
  An application can use the URL, type, ID, or action to invoke the
  content handler. The handler to be invoked is selected based on the type, ID,
  and action requested.
</P>

<P>The interactions between the invoking and invoked applications are
  carefully  managed so that applications can be active either in
  parallel or in sequence, depending on the Java runtime environment.
  The passing of parameters to the
  content handler and returning of results to the invoking application are
  managed when the content handler is finished with each request.
  If the resources and policy of the device allow concurrent execution,
  then the invoking and invoked applications may both be active at the
  same time. 
  In this case, the device will control the sharing of device
  resources such as keyboard, display, and media functions. </P>
<P>Each application executes in the appropriate runtime.
  For example, a MIDlet suite will run in a MIDP runtime.
  Typically, only a single MIDlet can be active 
  at a time.
  In this case, the MIDlet is instructed to exit so that the content 
  handler can start. When the content handler is finished with a
  request, if it is a MIDlet, it is instructed to exit so that the
  invoking application can be restarted to process the status and
  results. On CDC, a properly packaged Xlet or main program can be
  used.
  The invoking and invoked Xlets can be active at the same time as  
  supported by the Java runtime environment. </P>
<P>Non-Java applications may be integrated into the registration and
  invocation process. The device's browser is one of the most
  important applications that should be invokable by the content
  handler mechanism.
  The browser can use this mechanism to invoke other content handlers.
  The details of the integration and user interactions are beyond the
  scope of this specification, since they depend on the device and
  operating environment. </P> 

<h2>Use Cases</h2>
<P>Use cases can help illustrate the functions and behavior which are provided 
  by content handlers and are available to an application.</P>

<h3>Use Case 1: Distributing new game levels</h3>
<P>New game levels can be distributed as links on a web page 
  or in an email message. When the user invokes the link, the corresponding 
  game application is started and the game level automatically
  downloaded into the game.</P>

<h3>Use Case 2: Sending coupons to customers</h3>
<P> A software company can use Short Messaging Service (SMS) to
  periodically send discount coupons 
  to its customers. The SMS contains a link to the coupon. When the
  user invokes the link, the coupon application will show the coupon
  and display a preview. 
  The link can contain the account information for the store 
  to streamline ordering and payment. When the user chooses to pay for the 
  application, it starts the download and installation process.</P>

<h3><a name="use_case_3"></a>Use Case 3: Receiving a snapshot</h3>
<P>
  The user receives an SMS with a link to a snapshot.
  When the user invokes the link, the snapshot is displayed by
  the image viewer.</P>  
<p> If the application for the snapshot is not installed, some devices can 
  contact a provisioning server with the type of image and return a
  link to the application that can display it. Invoking the link will
  start its installation on the device
  and then chain to the application to display the snapshot. </p> 

<h3>Use Case 4: Buying a Music-Clip</h3>
<p>
  A content handler is a credit card handling application. It handles
  a user's digital credit-card information stored in the device. During
  a mobile payment scenario, a user checks out music-clips at a music
  site via the browser and proceeds to check out. The user has previously
  downloaded a credit card handling J2ME content handler from the
  wireless operator's site, which is used by the music site. The
  browser invokes the J2ME credit card handler at the time of
  payment.
  After purchase, the link to the content would be invoked
  to download and install the content. </p>

<h3>Use Case 5: Upgrading software with new features</h3>

<P> A game developer wants to keep users up-to-date on new
  capabilities. The game itself checks with the server to see if
  there are new features that match the user's experience and
  profile. A link for a game update is displayed if appropriate. When the
  user chooses to upgrade, invoking the link installs the new or
  updated application and restarts the game.</P>

<h3>Use Case 6: Invoking content stored on the device</h3>
<P> For a device with local content storage, such as audio, mp3, or image files, 
  a content browser could provide the organization of the
  content.
  When the user chooses some content, the browser could invoke the
  appropriate content handler.
  The browser could provide a choice of the actions for the user such
  as edit, view, or play the content. Installing new content 
  handlers can automatically add support for new types. </P>

<h3>Use Case 7: Invoking a specific application</h3>

<P> An application may want to provide easy integration with another
  application in the same suite. The application would invoke the
  messaging client on the device, which will be well known and can be
  invoked directly by using its content handler ID. This would be
  appropriate for common generic applications and also for specific
  linkages between applications. A typed document or content object
  does not have to exist to invoke the application.</P>

<h3><a name="use_case_8"></a>
  Use Case 8: Getting an email address from a local or remote phone book</h3>
<p>A user is composing an email and must look up an email address. The
  email application invokes the address book so the user can choose
  the address.
  If the desired address is not present, the user may choose to use
  another network information application to look it up.
  Once the address is found, it is returned and added 
  to the local address book.
  The user selects the address to return to the email client.</p>

<h2><a name="ref_arch"></a>Reference Architecture</H2>
<P>The following reference architecture provides a basis for
  discussing the interfaces and behavior of CHAPI.
  It is an example only; implementations are free
  to use other architectures and designs to meet the CHAPI and
  behavioral requirements. 
  The block diagram below indicates general relationships between the
  CHAPI package, the native operating system (OS), the Java Runtime
  environment (Configuration and Profiles), and other optional
  packages that may be present in an implementation.</P> 

<IMG SRC="javax/microedition/content/doc-files/chapi-arch.gif"
     NAME="chapi-arch" BORDER=0 WIDTH=399 HEIGHT=487>

<P> <strong>Figure 1: A Java and Native Runtime Environment Including
      the Content Handler API</strong> </P>
<P ALIGN=LEFT>The elements in Figure 1 are described below.</P>
<UL>
  <LI>
    <P> <B>Native OS:</B> The Native OS is responsible for
      interactions with the 
      hardware, and for providing abstractions for input/output, file access,
      networking, etc. </P>
  </LI>
  <LI>
    <P> <B>AMS:</B> The Application Management System (AMS) of the
      device is a generic term used to describe the component(s)
      responsible for installation, execution, and life-cycle
      management of applications. The AMS also includes 
      over-the-air provisioning of Java applications. Figure 1
      illustrates that in the case of CHAPI, AMS is also responsible
      for brokering invocations and message passing between Java and
      native runtime environments. This enables Java applications and
      content handlers to invoke native content handlers and
      vice-versa. </P> 
  </LI>
  <LI>
    <P> <B>Configuration (CLDC/CDC):</B> A J2ME configuration is
      defined as a set of optimized Java APIs, class libraries, and a
      virtual machine which targets a family of devices with similar
      size and capability requirements.
      CHAPI is compatible with all versions of the Connected Limited
      Device Configuration (CLDC) and the Connected Device
      Configuration (CDC). </P> 
  </LI>
  <LI>
    <P> <B>Profile (MIDP/FP/PBP/IMP):</B> A J2ME Profile targets a
      specific family of devices and provides APIs which are required
      in addition to the configuration APIs. CHAPI is compatible with
      all versions of the Mobile Information Device Profile (MIDP),
      Foundation Profile (FP), Personal Basis Profile (PBP),
      Personal Profile (PP), and Information Module Profile (IMP). </P>
  </LI>
  <LI>
    <P> <B>Other Optional Packages:</B> Other Optional Packages refers
      to the various implementations of other Java specifications that
      may be present in a CHAPI implementation.</P>
  </LI>
  <LI>
    <P> <B>Content Handler API (CHAPI):</B> CHAPI exposes the APIs
      that allow access to content handler instances, content
      represented by URI schemes or MIME-types. CHAPI also
      uses some of the AMS functions. </P> 
  </LI>
  <LI>
    <P> <B>Native (Non-Java) Applications:</B> Non-Java applications
      in the CHAPI context refer to content handlers.
      These applications execute in the native runtime or browser
      environment. </P>
  </LI>
  <LI>
    <P> <B>Java Applications:</B> Java applications in the CHAPI context refer
      to Java content handlers. </P>
  </LI>
</UL>

<H2>Terminology used in this specification</H2>
The Content Handler API uses the following terms:
<UL>
<LI><b>Access Restriction:</b> A content handling application can restrict
  which applications can access its content handlers.
<LI><b>Action:</b> An invoking application can request that the
  content handler perform an action on the content.
<LI><b>Action Name:</b> Locale-appropriate string to present an action
  to a user.
<LI><b>ActionNameMap:</b> A mapping between actions and action names for a
  single locale.
<LI><b>Application:</b> An application is a program that conforms to the 
  lifecycle of the platform. It has entry points that allow it to be started
  and stopped.  For MIDP, each MIDlet is an application.
<LI><b>Application Chaining:</b> The ability of an application to invoke
  another application and that application can invoke another and
  return results back up the chain.
<LI><b>Application ID:</b> A unique identifier for an application. 
<LI><b>Application Lifecycle:</b> The sequence of steps defined by the
  appropriate Java runtime environment for starting,
  stopping and controlling an application.
<LI><b>Application Package:</b> A bundle of one or more applications,
  each application includes classes, resources and meta-data
  describing the bundle and its requirements to run.
  Typically, a Java archive (JAR) and an application descriptor.
  The syntax and format is specific to a Java platform.
<LI><b>Arguments:</b> A sequence of strings passed from the invoking
  application to the content handling application which can be modified 
  and returned to invoking application.
<LI><b>Authentication:</b> The platform capability to verify the origin of 
  applications including content handler applications.
<LI><b>Authority:</b> A credential used to authenticate an application.
<LI><b>Background:</b> The state in which an application does not have
  access to the display and can not interact with the user.
<LI><b>Content</b>: Any text, image, sound, or other file or files identified 
by a URL that can be fetched and used by the device. 
<LI><b>ContentHandler:</b> A Java object containing the
  types, suffixes, actions and action names, etc. supported by a
  registered content handler.
<LI><b>Content Handler:</b> An application that registers itself
  to display or act on content based on content type, suffix, or
  content handler ID.
<LI><b>Content Handler ID:</b> A unique identifier for a content handler.
<LI><b>ContentHandlerListener:</b> An interface to be notified when a new
  request or response is available. 
<LI><b>ContentHandlerServer:</b> A content handler application uses this
  interface to process requests.
<LI><b>Content Type:</b> A string identifying the type of content,
  such as a MIME-type.
<LI><b>Dynamic Registration:</b> A content handler registration made
  using the API. 
<LI><b>Foreground:</b> The state in which an application has access to the
  display and can interact with the user.
<LI><b>Invocation:</b> A Java object containing the URL, type, ID, and arguments
  that are parameters in a Request or Response.
<LI><b>Invoking Application:</b> The application that invokes a request to a
  content handler.
<LI><b>Java runtime environment:</b> The Java runtime environment
  consists of the Java Virtual machine and libraries provided by
  the configuration, profiles and optional packages.
<LI><b>Locale String:</b> A string identifying a language, optional
  country, and optional variant.
<LI><b>Registration:</b> The types, suffixes, actions, actions names, and
  application classname registered for a content handler.
<LI><b>Registry:</b> A Java object that maintains the set of registered handlers
  and which is used to make an invocation request and get the response.
<LI><b>Request:</b> An Invocation object containing the parameters passed to
  a content handler. 
<LI><b>Response:</b> An Invocation object containing the result returned
  from a content handler. 
<LI><b>Static Registration:</b> A registration performed during installation.
<LI><b>Status:</b> The status of an Invocation request or response.
<LI><b>Suffix:</b> A short string compared with a URL to locate a content
  handler if specific type information is not available.
  For example, a file ending such as ".png".
</UL>

<H2>Digital Rights Management</H2>
<P>CHAPI will work with the DRM implemented on the device and shall
  not bypass any mechanisms of the device for implementing  
  or enforcing content controls.</P>

<h2>Application Interactions</h2>
<p>
  The following examples illustrate how the components described in
  the <a href="#ref_arch">reference  architecture</a>
  interact while processing selected use cases.</p>

<h3>Use Case 3: Receiving a snapshot</h3>

<P> <a href="#use_case_3">Use Case 3</a> addresses the need for an application 
to 
  dispatch a URL to the appropriate content handler, in this case a
  snapshot. The request is made without the invoking application
  being aware of the content type, or any need to supply additional
  arguments. Figure 2 illustrates how an implementation might support
  the APIs and shows the sequence of interactions between the
  components and an application and content handler which use the
  APIs. </P>

<IMG SRC="javax/microedition/content/doc-files/sequence-1.gif"
     NAME="Figure 2" BORDER=0 WIDTH=589 HEIGHT=773>
<P> <strong>Figure 2: Sequence of Interactions between Components in a Simple 
  Invocation </strong> </P>

<P> The sequence describes the application invoking the URL, the steps necessary 
  to identify the type of the content (<tt>.png</tt>), which the content 
handler is to 
  invoke, the steps the content handler uses, the details of starting the application, 
  and the return of status to the invoking application. The invoking application 

  and the content handler application can be running in parallel.</p>


    <P>1a. The application uses CHAPI to invoke the URL
      <code>http://host/app.png</code>.
      Since only the URL is supplied, the type information must
      be determined by accessing the URL.</P>
 
    <P>2a. The CHAPI implementation cooperates with the AMS to
      retrieve the content from the application server.</P>
 
    <P>2b. The content and type information are returned from the
      application server and is cached in cooperation with the AMS for
      use in step 7.</P>
 
    <P>3a. The type information is used to retrieve the content
      handler from the registry of types and handlers. </P>

    
<P>3b/1b. The CHAPI method returns to the application, indicating that the invocation 
  is proceeding.</P>
 
    <P>4. The AMS starts the content handler application, if it is
      not already active.</P>
 
    <P>5a. The content handler calls CHAPI to get the invocation
      parameters.</P>

    
<P>5b. An Invocation object is returned that provides access to the URL, type, 
  action, and other arguments.</P>
 
    <P>6a. The content handler uses the invocation object to open the
      content.</P>
 
    
<P>6b. The content saved in step 3 is made available to the application by using 
  a Generic Connection Framework Connection object.</P>
 
    <P>7. The application displays the information and interacts with the user
      as needed.</P>
 
    <P>8a. When the user has finished with the content, the completion
      status of the Invocation is set to return status to the invoking
      application.</P> 
 
    <P>8b. The method setting the completion status returns.</P>
 
    <P>9a. The application calls CHAPI to get the invocation
      response.</P>
 
    <P>9b. The invocation response is returned to the application. The
      application can now query the completion status.</P>
 

<h3>Use Case 8: Invocation Across Multiple Applications</h3>
<p><a href="#use_case_8">Use Case 8</a> describes an email address lookup
  that involves interactions between two CHAPI-enabled applications,
  the AMS, and a remote network service. The mail client makes
  a request for an email address. The local address book must handle
  that request and make an additional request to the network
  information application. The following sequence diagram illustrates
  the interactions. </p> 


<IMG SRC="javax/microedition/content/doc-files/sequence-3.gif"
     NAME="Figure 3" BORDER=0 WIDTH=599 HEIGHT=792>
<P> <strong>Figure 3: Sequence of Interactions between Three Applications </strong> 
</P>

<P>Figure 3 contains the steps needed for a MIDP application to invoke the 
  content 
  handler for some web content, such as an image. The invoking application and 
  the two content handler applications are MIDlets that, due to system 
constraints, 
  cannot execute in parallel. The sequence diagram illustrates how the life cycle 
  is used to start, stop, and restart the application and content handler. Note 
  that if the application and content handler could execute in parallel, then 
  steps 2, 7, 14, and 20 would not be necessary. 
<OL>
  <LI>
    <p>The email application uses CHAPI to invoke the type 
<code>text/vcard</code>. 
      The mapping from type to content handler ID is handled by the AMS. </P>
  </LI>
  <LI>
    <P>The application must exit to allow the content handler
      to run if the implementation does not support both applications
      running  at the same time.
    </P>
  </LI>
  <LI>
    <P>The AMS invokes the content handler to start the address book application.
    </P>
  </LI>
  <LI>
    <P>The address book content handler requests the Invocation
      to determine what it is being asked to do.
    </P>
  </LI>
  <LI>
    <P>The URL contains a query for "tom" so the address book displays
      the matching contents.  The user determines that the desired
      email address is not present and chooses a command to launch the
      network information application.
    </P>
  </LI>
  <LI>
    <P>The network information application is launched using the type of
      network information application, <code>text/vnd.411</code>. The original
      invocation must be saved until it receives a response from the network information
      lookup. </P>
  </LI>
  <LI>
    <P> The address book application must exit so that
      the network information application can be launched.
    </P>
  </LI>
  <LI>
    <P>The AMS invokes the network information application.
    </P>
  </LI>
  <LI>
    <P>The network information application retrieves its parameters,
      including the query for "tom" and displays the interface to the
      service which locates email addresses on the Internet.</P> 
  </LI>
  <LI>
    <P>The network information application queries the address from
      the Internet.</P>
  </LI>
  <LI>
    <P>The directory of email addresses from the Internet is displayed. The user
      selects an address to return. </P>
  </LI>
  <LI>
    <P>The selected address is set as the return value.
    </P>
  </LI>
  <LI>
    <P>The status of the latest request is set to OK. </P>
  </LI>
  <LI>
    <P>The network information application must exit so
      that the address book can be resumed.
    </P>
  </LI>
  <LI>
    <P>The AMS uses information saved in the request to re-invoke the
      address book. 
    </P>
  </LI>
  <LI>
    <P>The address book retrieves the response to its request for an email address 
      in step 6. </P>
  </LI>
  <LI>
    <P>The new address is added to the local address book and the
      user chooses it to address the current email.
    </P>
  </LI>
  <LI>
    <P>The chosen email address is returned as the result of the
      previous Invocation saved in step 6.
    </P>
  </LI>
  <LI>
    <P>The status of the previous request is set to OK.</P>
  </LI>
  <LI>
    <P>The address book application must exit so that the email client
      can be restarted. </P>
  </LI>
  <LI>
    <P>The invoking application information saved in the invocation is
      used to restart the email client.
    </P>
  </LI>
  <LI>
    <P>The email client retrieves the email address from the response
      and inserts it into the message being composed. </P>
  </LI>
</OL>

</BODY>
</HTML>
